please-upgrade-node

What is please-upgrade-node?

The please-upgrade-node package is designed to help Node.js developers ensure that their applications are run with a minimum required version of Node.js. It provides a simple way to enforce a version constraint, displaying a message to users to upgrade their Node.js version if the current environment does not meet the specified requirements. This is particularly useful for CLI tools or applications where the developer wants to prevent execution in unsupported Node.js environments.

What are please-upgrade-node's main functionalities?

Enforcing minimum Node.js version

This feature allows developers to specify a minimum Node.js version requirement in their package.json file. When the application or tool is run, please-upgrade-node checks the current Node.js version against the specified minimum version. If the current version is lower, it displays a message urging the user to upgrade their Node.js installation. The 'pkg' variable represents the package.json of the application, which should include a 'engines' field specifying the required Node.js version.

require('please-upgrade-node')(pkg)

Other packages similar to please-upgrade-node

check-node-version

Similar to please-upgrade-node, check-node-version allows developers to specify version requirements for Node.js, npm, and Yarn. It can be used as a command-line tool or integrated into scripts. Unlike please-upgrade-node, which is focused solely on Node.js versions, check-node-version provides broader version checking capabilities, making it suitable for projects that also need to enforce npm or Yarn version constraints.

engine-check

engine-check is another package that offers functionality similar to please-upgrade-node by enforcing engine version requirements specified in the package.json file. It can be used as a preinstall or prestart script to ensure that the Node.js environment meets the specified version requirements before proceeding. Compared to please-upgrade-node, engine-check provides a more automated approach to version enforcement, directly integrating with npm lifecycle scripts.

README

Please upgrade Node

:information_desk_person: show a message to your users to upgrade Node instead of a stacktrace

It's common for new Node users to miss or not understand engines warning when installing a CLI. This package displays a beginner-friendly message if their Node version is below the one expected.

$ node -v
0.12

$ modern-cli
modern-cli requires at least version 6 of Node, please upgrade

Support

If you like this project, you can support me on GitHub Sponsors

Usage

npm install please-upgrade-node

Add please-upgrade-node at the top of your CLI

#!/usr/bin/env node
const pkg = require('./package.json')
require('please-upgrade-node')(pkg) // <- Must run BEFORE requiring any other modules

// ...

Set in your package.json the required Node version

{
  "engines": {
    "node": ">=6"
  }
}

Important: >= is the only operator supported by please-upgrade-node (e.g. >=6, >=6.0, >=6.0.0).

Options

You can set custom exitCode and message function if needed

pleaseUpgradeNode(pkg, {
  exitCode: 0, // Default: 1
  message: function(requiredVersion) {
    return 'Oops this program require Node ' +  requiredVersion
  }
})

Important: to keep message function compatible with older versions of Node, avoid using ES6 features like => or string interpolation.

See also

• pkg-ok - :ok_hand: Prevents publishing a module with bad paths
• husky - :dog: Git hooks made easy
• update-notifier - Update notifications for your CLI app

Thanks to zeit/serve for the error message inspiration.

License

MIT - Typicode :cactus: - Patreon